
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
  "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">

<html xmlns="http://www.w3.org/1999/xhtml" lang="en">
  <head>
    <meta http-equiv="X-UA-Compatible" content="IE=Edge" />
    <meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
    <title>How to use Django with Apache and mod_wsgi &#8212; Django 2.2.12.dev20200304094918 documentation</title>
    <link rel="stylesheet" href="../../../_static/default.css" type="text/css" />
    <link rel="stylesheet" href="../../../_static/pygments.css" type="text/css" />
    <script type="text/javascript" id="documentation_options" data-url_root="../../../" src="../../../_static/documentation_options.js"></script>
    <script type="text/javascript" src="../../../_static/jquery.js"></script>
    <script type="text/javascript" src="../../../_static/underscore.js"></script>
    <script type="text/javascript" src="../../../_static/doctools.js"></script>
    <script type="text/javascript" src="../../../_static/language_data.js"></script>
    <link rel="index" title="Index" href="../../../genindex.html" />
    <link rel="search" title="Search" href="../../../search.html" />
    <link rel="next" title="Authenticating against Django’s user database from Apache" href="apache-auth.html" />
    <link rel="prev" title="How to use Django with uWSGI" href="uwsgi.html" />



 
<script type="text/javascript" src="../../../templatebuiltins.js"></script>
<script type="text/javascript">
(function($) {
    if (!django_template_builtins) {
       // templatebuiltins.js missing, do nothing.
       return;
    }
    $(document).ready(function() {
        // Hyperlink Django template tags and filters
        var base = "../../../ref/templates/builtins.html";
        if (base == "#") {
            // Special case for builtins.html itself
            base = "";
        }
        // Tags are keywords, class '.k'
        $("div.highlight\\-html\\+django span.k").each(function(i, elem) {
             var tagname = $(elem).text();
             if ($.inArray(tagname, django_template_builtins.ttags) != -1) {
                 var fragment = tagname.replace(/_/, '-');
                 $(elem).html("<a href='" + base + "#" + fragment + "'>" + tagname + "</a>");
             }
        });
        // Filters are functions, class '.nf'
        $("div.highlight\\-html\\+django span.nf").each(function(i, elem) {
             var filtername = $(elem).text();
             if ($.inArray(filtername, django_template_builtins.tfilters) != -1) {
                 var fragment = filtername.replace(/_/, '-');
                 $(elem).html("<a href='" + base + "#" + fragment + "'>" + filtername + "</a>");
             }
        });
    });
})(jQuery);</script>

  </head><body>

    <div class="document">
  <div id="custom-doc" class="yui-t6">
    <div id="hd">
      <h1><a href="../../../index.html">Django 2.2.12.dev20200304094918 documentation</a></h1>
      <div id="global-nav">
        <a title="Home page" href="../../../index.html">Home</a>  |
        <a title="Table of contents" href="../../../contents.html">Table of contents</a>  |
        <a title="Global index" href="../../../genindex.html">Index</a>  |
        <a title="Module index" href="../../../py-modindex.html">Modules</a>
      </div>
      <div class="nav">
    &laquo; <a href="uwsgi.html" title="How to use Django with uWSGI">previous</a>
     |
    <a href="../../index.html" title="“How-to” guides" accesskey="U">up</a>
   |
    <a href="apache-auth.html" title="Authenticating against Django’s user database from Apache">next</a> &raquo;</div>
    </div>

    <div id="bd">
      <div id="yui-main">
        <div class="yui-b">
          <div class="yui-g" id="howto-deployment-wsgi-modwsgi">
            
  <div class="section" id="s-how-to-use-django-with-apache-and-mod-wsgi">
<span id="how-to-use-django-with-apache-and-mod-wsgi"></span><h1>How to use Django with Apache and <code class="docutils literal notranslate"><span class="pre">mod_wsgi</span></code><a class="headerlink" href="#how-to-use-django-with-apache-and-mod-wsgi" title="Permalink to this headline">¶</a></h1>
<p>Deploying Django with <a class="reference external" href="https://httpd.apache.org/">Apache</a> and <a class="reference external" href="https://modwsgi.readthedocs.io/en/develop/">mod_wsgi</a> is a tried and tested way to get
Django into production.</p>
<p>mod_wsgi is an Apache module which can host any Python <a class="reference external" href="https://wsgi.readthedocs.io/en/latest/">WSGI</a> application,
including Django. Django will work with any version of Apache which supports
mod_wsgi.</p>
<p>The <a class="reference external" href="https://modwsgi.readthedocs.io/">official mod_wsgi documentation</a> is your source for all the details about
how to use mod_wsgi. You’ll probably want to start with the <a class="reference external" href="https://modwsgi.readthedocs.io/en/develop/installation.html">installation and
configuration documentation</a>.</p>
<div class="section" id="s-basic-configuration">
<span id="basic-configuration"></span><h2>Basic configuration<a class="headerlink" href="#basic-configuration" title="Permalink to this headline">¶</a></h2>
<p>Once you’ve got mod_wsgi installed and activated, edit your Apache server’s
<a class="reference external" href="https://wiki.apache.org/httpd/DistrosDefaultLayout">httpd.conf</a> file and add the following. If you are using a version of Apache
older than 2.4, replace <code class="docutils literal notranslate"><span class="pre">Require</span> <span class="pre">all</span> <span class="pre">granted</span></code> with <code class="docutils literal notranslate"><span class="pre">Allow</span> <span class="pre">from</span> <span class="pre">all</span></code> and
also add the line <code class="docutils literal notranslate"><span class="pre">Order</span> <span class="pre">deny,allow</span></code> above it.</p>
<div class="highlight-apache notranslate"><div class="highlight"><pre><span></span><span class="nb">WSGIScriptAlias</span> / <span class="sx">/path/to/mysite.com/mysite/wsgi.py</span>
<span class="nb">WSGIPythonHome</span> <span class="sx">/path/to/venv</span>
<span class="nb">WSGIPythonPath</span> <span class="sx">/path/to/mysite.com</span>

<span class="nt">&lt;Directory</span> <span class="s">/path/to/mysite.com/mysite</span><span class="nt">&gt;</span>
<span class="nt">&lt;Files</span> <span class="s">wsgi.py</span><span class="nt">&gt;</span>
<span class="nb">Require</span> <span class="k">all</span> granted
<span class="nt">&lt;/Files&gt;</span>
<span class="nt">&lt;/Directory&gt;</span>
</pre></div>
</div>
<p>The first bit in the <code class="docutils literal notranslate"><span class="pre">WSGIScriptAlias</span></code> line is the base URL path you want to
serve your application at (<code class="docutils literal notranslate"><span class="pre">/</span></code> indicates the root url), and the second is the
location of a “WSGI file” – see below – on your system, usually inside of
your project package (<code class="docutils literal notranslate"><span class="pre">mysite</span></code> in this example). This tells Apache to serve
any request below the given URL using the WSGI application defined in that
file.</p>
<p>If you install your project’s Python dependencies inside a <a class="reference external" href="https://virtualenv.pypa.io/">virtualenv</a>, add
the path to the virtualenv using <code class="docutils literal notranslate"><span class="pre">WSGIPythonHome</span></code>. See the <a class="reference external" href="https://modwsgi.readthedocs.io/en/develop/user-guides/virtual-environments.html">mod_wsgi
virtualenv guide</a> for more details.</p>
<p>The <code class="docutils literal notranslate"><span class="pre">WSGIPythonPath</span></code> line ensures that your project package is available for
import on the Python path; in other words, that <code class="docutils literal notranslate"><span class="pre">import</span> <span class="pre">mysite</span></code> works.</p>
<p>The <code class="docutils literal notranslate"><span class="pre">&lt;Directory&gt;</span></code> piece just ensures that Apache can access your
<code class="file docutils literal notranslate"><span class="pre">wsgi.py</span></code> file.</p>
<p>Next we’ll need to ensure this <code class="file docutils literal notranslate"><span class="pre">wsgi.py</span></code> with a WSGI application object
exists. As of Django version 1.4, <a class="reference internal" href="../../../ref/django-admin.html#django-admin-startproject"><code class="xref std std-djadmin docutils literal notranslate"><span class="pre">startproject</span></code></a> will have created one
for you; otherwise, you’ll need to create it. See the <a class="reference internal" href="index.html"><span class="doc">WSGI overview
documentation</span></a> for the default contents you
should put in this file, and what else you can add to it.</p>
<div class="admonition warning">
<p class="first admonition-title">Warning</p>
<p>If multiple Django sites are run in a single mod_wsgi process, all of them
will use the settings of whichever one happens to run first. This can be
solved by changing:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="n">os</span><span class="o">.</span><span class="n">environ</span><span class="o">.</span><span class="n">setdefault</span><span class="p">(</span><span class="s2">&quot;DJANGO_SETTINGS_MODULE&quot;</span><span class="p">,</span> <span class="s2">&quot;{{ project_name }}.settings&quot;</span><span class="p">)</span>
</pre></div>
</div>
<p>in <code class="docutils literal notranslate"><span class="pre">wsgi.py</span></code>, to:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="n">os</span><span class="o">.</span><span class="n">environ</span><span class="p">[</span><span class="s2">&quot;DJANGO_SETTINGS_MODULE&quot;</span><span class="p">]</span> <span class="o">=</span> <span class="s2">&quot;{{ project_name }}.settings&quot;</span>
</pre></div>
</div>
<p class="last">or by <a class="reference internal" href="#daemon-mode"><span class="std std-ref">using mod_wsgi daemon mode</span></a> and ensuring that each
site runs in its own daemon process.</p>
</div>
<div class="admonition-fixing-unicodeencodeerror-for-file-uploads admonition">
<p class="first admonition-title">Fixing <code class="docutils literal notranslate"><span class="pre">UnicodeEncodeError</span></code> for file uploads</p>
<p>If you get a <code class="docutils literal notranslate"><span class="pre">UnicodeEncodeError</span></code> when uploading files with file names
that contain non-ASCII characters, make sure Apache is configured to accept
non-ASCII file names:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="n">export</span> <span class="n">LANG</span><span class="o">=</span><span class="s1">&#39;en_US.UTF-8&#39;</span>
<span class="n">export</span> <span class="n">LC_ALL</span><span class="o">=</span><span class="s1">&#39;en_US.UTF-8&#39;</span>
</pre></div>
</div>
<p>A common location to put this configuration is <code class="docutils literal notranslate"><span class="pre">/etc/apache2/envvars</span></code>.</p>
<p class="last">See the <a class="reference internal" href="../../../ref/unicode.html#unicode-files"><span class="std std-ref">Files</span></a> section of the Unicode reference guide for
details.</p>
</div>
</div>
<div class="section" id="s-using-mod-wsgi-daemon-mode">
<span id="s-daemon-mode"></span><span id="using-mod-wsgi-daemon-mode"></span><span id="daemon-mode"></span><h2>Using <code class="docutils literal notranslate"><span class="pre">mod_wsgi</span></code> daemon mode<a class="headerlink" href="#using-mod-wsgi-daemon-mode" title="Permalink to this headline">¶</a></h2>
<p>“Daemon mode” is the recommended mode for running mod_wsgi (on non-Windows
platforms). To create the required daemon process group and delegate the
Django instance to run in it, you will need to add appropriate
<code class="docutils literal notranslate"><span class="pre">WSGIDaemonProcess</span></code> and <code class="docutils literal notranslate"><span class="pre">WSGIProcessGroup</span></code> directives. A further change
required to the above configuration if you use daemon mode is that you can’t
use <code class="docutils literal notranslate"><span class="pre">WSGIPythonPath</span></code>; instead you should use the <code class="docutils literal notranslate"><span class="pre">python-path</span></code> option to
<code class="docutils literal notranslate"><span class="pre">WSGIDaemonProcess</span></code>, for example:</p>
<div class="highlight-apache notranslate"><div class="highlight"><pre><span></span><span class="nb">WSGIDaemonProcess</span> example.com python-home=/path/to/venv python-path=/path/to/mysite.com
<span class="nb">WSGIProcessGroup</span> example.com
</pre></div>
</div>
<p>If you want to serve your project in a subdirectory
(<code class="docutils literal notranslate"><span class="pre">https://example.com/mysite</span></code> in this example), you can add <code class="docutils literal notranslate"><span class="pre">WSGIScriptAlias</span></code>
to the configuration above:</p>
<div class="highlight-apache notranslate"><div class="highlight"><pre><span></span><span class="nb">WSGIScriptAlias</span> <span class="sx">/mysite</span> <span class="sx">/path/to/mysite.com/mysite/wsgi.py</span> process-group=example.com
</pre></div>
</div>
<p>See the official mod_wsgi documentation for <a class="reference external" href="https://modwsgi.readthedocs.io/en/develop/user-guides/quick-configuration-guide.html#delegation-to-daemon-process">details on setting up daemon
mode</a>.</p>
</div>
<div class="section" id="s-serving-files">
<span id="s-id1"></span><span id="serving-files"></span><span id="id1"></span><h2>Serving files<a class="headerlink" href="#serving-files" title="Permalink to this headline">¶</a></h2>
<p>Django doesn’t serve files itself; it leaves that job to whichever Web
server you choose.</p>
<p>We recommend using a separate Web server – i.e., one that’s not also running
Django – for serving media. Here are some good choices:</p>
<ul class="simple">
<li><a class="reference external" href="https://nginx.org/en/">Nginx</a></li>
<li>A stripped-down version of <a class="reference external" href="https://httpd.apache.org/">Apache</a></li>
</ul>
<p>If, however, you have no option but to serve media files on the same Apache
<code class="docutils literal notranslate"><span class="pre">VirtualHost</span></code> as Django, you can set up Apache to serve some URLs as
static media, and others using the mod_wsgi interface to Django.</p>
<p>This example sets up Django at the site root, but serves <code class="docutils literal notranslate"><span class="pre">robots.txt</span></code>,
<code class="docutils literal notranslate"><span class="pre">favicon.ico</span></code>, and anything in the <code class="docutils literal notranslate"><span class="pre">/static/</span></code> and <code class="docutils literal notranslate"><span class="pre">/media/</span></code> URL space as
a static file. All other URLs will be served using mod_wsgi:</p>
<div class="highlight-apache notranslate"><div class="highlight"><pre><span></span><span class="nb">Alias</span> <span class="sx">/robots.txt</span> <span class="sx">/path/to/mysite.com/static/robots.txt</span>
<span class="nb">Alias</span> <span class="sx">/favicon.ico</span> <span class="sx">/path/to/mysite.com/static/favicon.ico</span>

<span class="nb">Alias</span> <span class="sx">/media/</span> <span class="sx">/path/to/mysite.com/media/</span>
<span class="nb">Alias</span> <span class="sx">/static/</span> <span class="sx">/path/to/mysite.com/static/</span>

<span class="nt">&lt;Directory</span> <span class="s">/path/to/mysite.com/static</span><span class="nt">&gt;</span>
<span class="nb">Require</span> <span class="k">all</span> granted
<span class="nt">&lt;/Directory&gt;</span>

<span class="nt">&lt;Directory</span> <span class="s">/path/to/mysite.com/media</span><span class="nt">&gt;</span>
<span class="nb">Require</span> <span class="k">all</span> granted
<span class="nt">&lt;/Directory&gt;</span>

<span class="nb">WSGIScriptAlias</span> / <span class="sx">/path/to/mysite.com/mysite/wsgi.py</span>

<span class="nt">&lt;Directory</span> <span class="s">/path/to/mysite.com/mysite</span><span class="nt">&gt;</span>
<span class="nt">&lt;Files</span> <span class="s">wsgi.py</span><span class="nt">&gt;</span>
<span class="nb">Require</span> <span class="k">all</span> granted
<span class="nt">&lt;/Files&gt;</span>
<span class="nt">&lt;/Directory&gt;</span>
</pre></div>
</div>
<p>If you are using a version of Apache older than 2.4, replace
<code class="docutils literal notranslate"><span class="pre">Require</span> <span class="pre">all</span> <span class="pre">granted</span></code> with <code class="docutils literal notranslate"><span class="pre">Allow</span> <span class="pre">from</span> <span class="pre">all</span></code> and also add the line
<code class="docutils literal notranslate"><span class="pre">Order</span> <span class="pre">deny,allow</span></code> above it.</p>
</div>
<div class="section" id="s-serving-the-admin-files">
<span id="s-id3"></span><span id="serving-the-admin-files"></span><span id="id3"></span><h2>Serving the admin files<a class="headerlink" href="#serving-the-admin-files" title="Permalink to this headline">¶</a></h2>
<p>When <a class="reference internal" href="../../../ref/contrib/staticfiles.html#module-django.contrib.staticfiles" title="django.contrib.staticfiles: An app for handling static files."><code class="xref py py-mod docutils literal notranslate"><span class="pre">django.contrib.staticfiles</span></code></a> is in <a class="reference internal" href="../../../ref/settings.html#std:setting-INSTALLED_APPS"><code class="xref std std-setting docutils literal notranslate"><span class="pre">INSTALLED_APPS</span></code></a>, the
Django development server automatically serves the static files of the
admin app (and any other installed apps). This is however not the case when you
use any other server arrangement. You’re responsible for setting up Apache, or
whichever Web server you’re using, to serve the admin files.</p>
<p>The admin files live in (<code class="file docutils literal notranslate"><span class="pre">django/contrib/admin/static/admin</span></code>) of the
Django distribution.</p>
<p>We <strong>strongly</strong> recommend using <a class="reference internal" href="../../../ref/contrib/staticfiles.html#module-django.contrib.staticfiles" title="django.contrib.staticfiles: An app for handling static files."><code class="xref py py-mod docutils literal notranslate"><span class="pre">django.contrib.staticfiles</span></code></a> to handle the
admin files (along with a Web server as outlined in the previous section; this
means using the <a class="reference internal" href="../../../ref/contrib/staticfiles.html#django-admin-collectstatic"><code class="xref std std-djadmin docutils literal notranslate"><span class="pre">collectstatic</span></code></a> management command to collect the
static files in <a class="reference internal" href="../../../ref/settings.html#std:setting-STATIC_ROOT"><code class="xref std std-setting docutils literal notranslate"><span class="pre">STATIC_ROOT</span></code></a>, and then configuring your Web server to
serve <a class="reference internal" href="../../../ref/settings.html#std:setting-STATIC_ROOT"><code class="xref std std-setting docutils literal notranslate"><span class="pre">STATIC_ROOT</span></code></a> at <a class="reference internal" href="../../../ref/settings.html#std:setting-STATIC_URL"><code class="xref std std-setting docutils literal notranslate"><span class="pre">STATIC_URL</span></code></a>), but here are three
other approaches:</p>
<ol class="arabic simple">
<li>Create a symbolic link to the admin static files from within your
document root (this may require <code class="docutils literal notranslate"><span class="pre">+FollowSymLinks</span></code> in your Apache
configuration).</li>
<li>Use an <code class="docutils literal notranslate"><span class="pre">Alias</span></code> directive, as demonstrated above, to alias the appropriate
URL (probably <a class="reference internal" href="../../../ref/settings.html#std:setting-STATIC_URL"><code class="xref std std-setting docutils literal notranslate"><span class="pre">STATIC_URL</span></code></a> + <code class="docutils literal notranslate"><span class="pre">admin/</span></code>) to the actual location of
the admin files.</li>
<li>Copy the admin static files so that they live within your Apache
document root.</li>
</ol>
</div>
<div class="section" id="s-authenticating-against-django-s-user-database-from-apache">
<span id="authenticating-against-django-s-user-database-from-apache"></span><h2>Authenticating against Django’s user database from Apache<a class="headerlink" href="#authenticating-against-django-s-user-database-from-apache" title="Permalink to this headline">¶</a></h2>
<p>Django provides a handler to allow Apache to authenticate users directly
against Django’s authentication backends. See the <a class="reference internal" href="apache-auth.html"><span class="doc">mod_wsgi authentication
documentation</span></a>.</p>
</div>
</div>


          </div>
        </div>
      </div>
      
        
          <div class="yui-b" id="sidebar">
            
      <div class="sphinxsidebar" role="navigation" aria-label="main navigation">
        <div class="sphinxsidebarwrapper">
  <h3><a href="../../../contents.html">Table of Contents</a></h3>
  <ul>
<li><a class="reference internal" href="#">How to use Django with Apache and <code class="docutils literal notranslate"><span class="pre">mod_wsgi</span></code></a><ul>
<li><a class="reference internal" href="#basic-configuration">Basic configuration</a></li>
<li><a class="reference internal" href="#using-mod-wsgi-daemon-mode">Using <code class="docutils literal notranslate"><span class="pre">mod_wsgi</span></code> daemon mode</a></li>
<li><a class="reference internal" href="#serving-files">Serving files</a></li>
<li><a class="reference internal" href="#serving-the-admin-files">Serving the admin files</a></li>
<li><a class="reference internal" href="#authenticating-against-django-s-user-database-from-apache">Authenticating against Django’s user database from Apache</a></li>
</ul>
</li>
</ul>

  <h4>Previous topic</h4>
  <p class="topless"><a href="uwsgi.html"
                        title="previous chapter">How to use Django with uWSGI</a></p>
  <h4>Next topic</h4>
  <p class="topless"><a href="apache-auth.html"
                        title="next chapter">Authenticating against Django’s user database from Apache</a></p>
  <div role="note" aria-label="source link">
    <h3>This Page</h3>
    <ul class="this-page-menu">
      <li><a href="../../../_sources/howto/deployment/wsgi/modwsgi.txt"
            rel="nofollow">Show Source</a></li>
    </ul>
   </div>
<div id="searchbox" style="display: none" role="search">
  <h3>Quick search</h3>
    <div class="searchformwrapper">
    <form class="search" action="../../../search.html" method="get">
      <input type="text" name="q" />
      <input type="submit" value="Go" />
      <input type="hidden" name="check_keywords" value="yes" />
      <input type="hidden" name="area" value="default" />
    </form>
    </div>
</div>
<script type="text/javascript">$('#searchbox').show(0);</script>
        </div>
      </div>
              <h3>Last update:</h3>
              <p class="topless">Mar 04, 2020</p>
          </div>
        
      
    </div>

    <div id="ft">
      <div class="nav">
    &laquo; <a href="uwsgi.html" title="How to use Django with uWSGI">previous</a>
     |
    <a href="../../index.html" title="“How-to” guides" accesskey="U">up</a>
   |
    <a href="apache-auth.html" title="Authenticating against Django’s user database from Apache">next</a> &raquo;</div>
    </div>
  </div>

      <div class="clearer"></div>
    </div>
  </body>
</html>